feat(color): add es-toolkit/color module by dayongkr · Pull Request #1683 · toss/es-toolkit

dayongkr · 2026-04-05T07:28:24Z

Summary

Add es-toolkit/color subpath for terminal color utilities
Fixes known picocolors bugs: FORCE_COLOR=0 handling, process ReferenceError, CI pipe detection
Supports 16 basic colors, 256-color, RGB, and Hex
Includes stripAnsi, createColors, colorLevel, isColorSupported
Pre-configured color object for direct usage (color.red('hello'))
FORCE_COLOR / NO_COLOR spec compliant
55 tests, 100% coverage
Documentation in 4 languages (en, ko, ja, zh_hans)

Test plan

yarn vitest run src/color/ — all 55 tests pass
yarn lint — no errors in src/color/
tsc --noEmit — no type errors
yarn build — dist/color/ generated correctly
Verify docs render at /reference/color/color

Add a new `es-toolkit/color` subpath with ANSI terminal color utilities: - 16 basic colors, bright variants, and background colors - Extended colors: ansi256, rgb, hex - Color level detection (FORCE_COLOR, NO_COLOR, TTY, COLORTERM, TERM) - stripAnsi utility - createColors factory for custom instances - Pre-configured `color` object for direct usage

Add reference docs for color, createColors, colorLevel, and stripAnsi in English, Korean, Japanese, and Chinese. Update sidebar configs.

vercel · 2026-04-05T07:28:31Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
es-toolkit	Ready	Preview, Comment	Apr 17, 2026 5:52am

parseInt('abcxyz', 16) silently parses 'abc' and ignores 'xyz'. Switch to Number('0x' + str) which returns NaN for any non-hex character.

Validate hex strings with /^[0-9a-fA-F]{3}$|^[0-9a-fA-F]{6}$/ instead of Number('0x' + str). Only #RGB and #RRGGBB are accepted — #RGBA and #RRGGBBAA are excluded because ANSI terminals don't support alpha.

- Rename stripAnsi to stripColor to clarify SGR-only scope - Add ./color to ENTRYPOINTS in check-dist.spec.ts - Document that colorLevel is evaluated once at import time

codecov-commenter · 2026-04-10T06:22:02Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.97%. Comparing base (b4c3cb4) to head (5529c76).

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #1683    +/-   ##
========================================
  Coverage   99.97%   99.97%            
========================================
  Files         497      548    +51     
  Lines        4662     4777   +115     
  Branches     1348     1369    +21     
========================================
+ Hits         4661     4776   +115     
  Misses          1        1

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

raon0211 · 2026-04-10T06:28:46Z

+    const str = toString(text);
+
+    if (str === '') {
+      return '';
+    }
+


What about requiring strings in text and removing this logic?

raon0211 · 2026-04-10T06:42:36Z

@@ -0,0 +1,93 @@
+// @vitest-environment node


There might be some edge cases here -- I think we need to make the test cases more complete.

raon0211 · 2026-04-10T06:43:07Z

+ * const noColor = createColors(false);
+ * noColor.red('hello'); // 'hello'
+ */
+export function createColors(enabled?: boolean): Colors {


What about we make these into functions like this?

export function reset(str: string) { if (detectColorLevel()) { return str; } return formatWithColor(str, '\x1b[0m', '\x1b[0m'); }

import colors from 'es-toolkit/colors';

I think we also have to provide this too

import * as colors from './colors'; export default colors;

Require callers to pass strings to color functions (no more `unknown` coercion via `String(text)`). This matches es-toolkit's stricter API philosophy and removes a tiny per-call cost. Split the monolithic `formatter.ts` into `createFormatter.ts` (the factory) and `parseHex.ts` (the hex parser) so each concern has its own file and spec.

Each color function (red, bold, hex, …) now lives in its own file with its own spec, enabling tree-shaking when users only need one or two utilities. The `createColors(enabled)` factory is removed — runtime toggling was not a real need. `FORCE_COLOR`/`NO_COLOR` environment variables and auto-detection cover the common cases; tests force enable via `vi.mock('./colorLevel.ts')`. Usage: import { red, bold, hex } from 'es-toolkit/color'; import color from 'es-toolkit/color'; red('error'); color.bold(color.red('error')); Internally, a shared `makeColor` factory wires each utility to `createFormatter` when color is supported, or an identity passthrough otherwise.

Backgrounds wrapped across CRLF (`\r\n`) previously left the `\r` inside the background scope, which could render incorrectly on terminals that reset cursor position on CR. Match chalk's behavior by handling `\r?\n` as one atomic newline. Also add a spec for the `makeColor` disabled path to bring the color module to 100% branch coverage.

Rewrite the color reference in all four languages to list every utility up front and show the new import patterns: import { red } from 'es-toolkit/color'; import color from 'es-toolkit/color'; Remove the `createColors` page since the factory was dropped.

…trol-regex The regex literal `/\u001b\[[0-9;]*m/g` tripped ESLint's `no-control-regex` rule because the escape sequence resolved to a control character. Build the pattern through `RegExp` with `String.fromCharCode(0x1b)` so the control byte stays out of the source at lint time. Also update the JSDoc example to use the new individual imports.

The `Colors` interface was the return type of the removed `createColors` factory and has no remaining callers.

raon0211 · 2026-04-17T06:18:36Z

+
+    // Re-open the outer style when a nested call with the same color
+    // inserts a close code inside the text.
+    if (open !== close && result.includes(close)) {


Why is open !== close needed here?

raon0211 · 2026-04-17T06:29:32Z

+ * 7. Node.js hasColors() — Runtime API (Node 11.13+) for accurate detection
+ * 8. Default — Basic 16 colors if none of the above matched
+ */
+export function detectColorLevel(): ColorLevel {


I think we have to simplify this function.

dayongkr added 2 commits April 5, 2026 16:10

docs(color): add documentation for es-toolkit/color in 4 languages

1e5a4cf

Add reference docs for color, createColors, colorLevel, and stripAnsi in English, Korean, Japanese, and Chinese. Update sidebar configs.

[autofix.ci] apply automated fixes

d4a78ad

vercel Bot deployed to Preview April 5, 2026 07:35 View deployment

fix(color): use strict hex parsing to reject partially valid strings

01462b6

parseInt('abcxyz', 16) silently parses 'abc' and ignores 'xyz'. Switch to Number('0x' + str) which returns NaN for any non-hex character.

vercel Bot deployed to Preview April 5, 2026 07:45 View deployment

refactor(color): use regex for hex validation per CSS Color Level 4

2a273a2

Validate hex strings with /^[0-9a-fA-F]{3}$|^[0-9a-fA-F]{6}$/ instead of Number('0x' + str). Only #RGB and #RRGGBB are accepted — #RGBA and #RRGGBBAA are excluded because ANSI terminals don't support alpha.

vercel Bot deployed to Preview April 5, 2026 07:52 View deployment

dayongkr marked this pull request as ready for review April 10, 2026 05:41

dayongkr requested a review from raon0211 as a code owner April 10, 2026 05:41

refactor(color): rename stripAnsi to stripColor and fix check-dist test

06899b0

- Rename stripAnsi to stripColor to clarify SGR-only scope - Add ./color to ENTRYPOINTS in check-dist.spec.ts - Document that colorLevel is evaluated once at import time

vercel Bot deployed to Preview April 10, 2026 06:24 View deployment

raon0211 reviewed Apr 10, 2026

View reviewed changes

dayongkr added 2 commits April 17, 2026 13:07

vercel Bot deployed to Preview April 17, 2026 04:16 View deployment

vercel Bot deployed to Preview April 17, 2026 04:32 View deployment

dayongkr and others added 2 commits April 17, 2026 13:51

[autofix.ci] apply automated fixes

9885876

vercel Bot deployed to Preview April 17, 2026 04:57 View deployment

vercel Bot deployed to Preview April 17, 2026 05:45 View deployment

refactor(color): drop unused Colors interface

5f8908b

The `Colors` interface was the return type of the removed `createColors` factory and has no remaining callers.

vercel Bot deployed to Preview April 17, 2026 05:52 View deployment

raon0211 reviewed Apr 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(color): add es-toolkit/color module#1683

feat(color): add es-toolkit/color module#1683
dayongkr wants to merge 13 commits intomainfrom
feat/color

dayongkr commented Apr 5, 2026

Uh oh!

vercel Bot commented Apr 5, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Apr 10, 2026 •

edited

Loading

Uh oh!

raon0211 Apr 10, 2026

Uh oh!

raon0211 Apr 10, 2026

Uh oh!

raon0211 Apr 10, 2026 •

edited

Loading

Uh oh!

raon0211 Apr 10, 2026

Uh oh!

raon0211 Apr 10, 2026

Uh oh!

raon0211 Apr 17, 2026

Uh oh!

raon0211 Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dayongkr commented Apr 5, 2026

Summary

Test plan

Uh oh!

vercel Bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

raon0211 Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

raon0211 Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

raon0211 Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raon0211 Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

raon0211 Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

raon0211 Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

raon0211 Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Apr 5, 2026 •

edited

Loading

codecov-commenter commented Apr 10, 2026 •

edited

Loading

raon0211 Apr 10, 2026 •

edited

Loading